%
% Copyright (c) 2009-2010,2013 LAAS/CNRS
% All rights reserved.
%
% Permission to use, copy, modify, and distribute this software for any purpose
% with or without   fee is hereby granted, provided   that the above  copyright
% notice and this permission notice appear in all copies.
%
% THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
% REGARD TO THIS  SOFTWARE INCLUDING ALL  IMPLIED WARRANTIES OF MERCHANTABILITY
% AND FITNESS. IN NO EVENT SHALL THE AUTHOR  BE LIABLE FOR ANY SPECIAL, DIRECT,
% INDIRECT, OR CONSEQUENTIAL DAMAGES OR  ANY DAMAGES WHATSOEVER RESULTING  FROM
% LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
% OTHER TORTIOUS ACTION,   ARISING OUT OF OR IN    CONNECTION WITH THE USE   OR
% PERFORMANCE OF THIS SOFTWARE.
%
%                                             Anthony Mallet on Sun Jan 11 2009
%

\section{Using robotpkg} % -------------------------------------------------

After obtaining \robotpkg, the  {\tt robotpkg} directory now  contains a set of
packages, organized   into  categories.  You can   browse  the online  index of
packages, or run {\tt  make index} from the {\tt  robotpkg} directory to  build
local {\tt index.html}  files for all  packages, viewable with any web  browser
such as {\tt lynx} or {\tt firefox}.

\robotpkg is  essentially based on the  {\tt make(1)} program.  All actions are
triggered by invoking {\tt make} with the proper target. The following sections
document          the           most          useful          ones          and
\xref{section:using:targets}{section~\ref{section:using:targets}} recaps a more
comprehensive list.


\subsection{Building packages from source} % -------------------------------

The  first step for  building  a  package  is  downloading the {\em  distfiles}
(i.e. the unmodified  source). If they have not  yet been downloaded, \robotpkg
will  fetch them automatically  and place them  in the {\tt robotpkg/distfiles}
directory.

Once the software  has  been downloaded,  any  patches will be applied  and the
package will  be compiled for  you.  This may  take some time depending on your
computer, and how many other packages the software depends on and their compile
time.

For  example,  type the following  commands  at the shell   prompt to build the
robotpkg documentation package:

\begin{verbatim}
% cd /opt/openrobots/robotpkg
% cd doc/robotpkg
% make
\end{verbatim}

The next  stage is  to  actually install the newly   compiled package onto your
system. While you   are still in  the directory  for whatever package  you  are
installing, you can do this by entering:

\begin{verbatim}
% make install
\end{verbatim}

Installing the package on your system does  not require you  to be root (except
for a few specific  packages). However, if   you bootstraped with a  prefix for
which   you  don't   have  writing   permissions,    \robotpkg   has a     {\rm
just-in-time-sudo}  feature,  which allows you to  become  {\tt  root}  for the
actual installation step.

That's it, the software should now be installed   under  the prefix  of the
packages tree --- {\tt /opt/openrobots} by default --- and setup for use.

You can now enter:

\begin{verbatim}
% make clean
\end{verbatim}

to remove the compiled files in the work  directory, as you shouldn't need them
any more. If  other packages were also  added to your system (dependencies)  to
allow your program to compile, you can also tidy these up with the command:

\begin{verbatim}
% make clean-depends
\end{verbatim}

Since  the three tasks of building,  installing and  cleaning correspond to the
typical usage of \robotpkg, a helper target doing all these tasks exists and is
called {\tt update}. Thus,  to intall a package  with a single command, you can
simply run:

\begin{verbatim}
% make update
\end{verbatim}

In addition, {\tt  make update} will  also recompile all the installed packages
that were depending on the package that you are updating. This can be quite
time consuming if you are updating a low-level package. Also, note that all
packages that depend on the package you are updating will be deinstalled
first and unavailable in your system until all packages are recompiled and
reinstalled.

%
%    <para>Some packages look in &mk.conf; to
%    alter some configuration options at build time.  Have a look at
%    <filename>pkgsrc/mk/defaults/mk.conf</filename> to get an overview
%    of what will be set there by default.  Environment variables such
%    as <varname>LOCALBASE</varname> can be set in
%    &mk.conf; to save having to remember to
%    set them each time you want to use pkgsrc.</para>
%

Occasionally, people want to ``look under the covers'' to see  what is going on
when a  package  is building  or being  installed.  This may  be for  debugging
purposes, or  out  of simple curiosity. A  number  of utility values have  been
added to help with this.

\begin{enumerate}

\item If you invoke the {\tt make} command with {\tt PKG\_DEBUG\_LEVEL=1}, then
      a huge amount of information will be displayed. For example,

\begin{verbatim}
% make patch PKG_DEBUG_LEVEL=1
\end{verbatim}

      will show all the commands that are invoked, up to and including the
      ``patch'' stage. Using {\tt PKG\_DEBUG\_LEVEL=2} will give you even
      more details.

\item If you want to know the value of a certain {\tt make} definition, then
   the {\tt VARNAME} variable   should be used,  in  conjunction with the  {\tt
   show-var} target.  e.g.  to show the  expansion  of the  {\tt make} variable
   {\tt LOCALBASE}:

\begin{verbatim}
% make show-var VARNAME=LOCALBASE
\end{verbatim}

\end{enumerate}

%    <para>If you want to install a binary package that you've either
%    created yourself (see next section), that you put into
%    pkgsrc/packages manually or that is located on a remote FTP
%    server, you can use the "bin-install" target. This target will
%    install a binary package - if available - via &man.pkg.add.1;,
%    else do a <command>make package</command>.  The list of remote FTP
%    sites searched is kept in the variable
%    <varname>BINPKG_SITES</varname>, which defaults to
%    ftp.NetBSD.org. Any flags that should be added to &man.pkg.add.1;
%    can be put into <varname>BIN_INSTALL_FLAGS</varname>.  See
%    <filename>pkgsrc/mk/defaults/mk.conf</filename> for more
%    details.</para>


%    <para>A final word of warning: If you set up a system that has a
%    non-standard setting for <varname>LOCALBASE</varname>, be sure to
%    set that before any packages are installed, as you cannot use
%    several directories for the same purpose. Doing so will result in
%    pkgsrc not being able to properly detect your installed packages,
%    and fail miserably. Note also that precompiled binary packages are
%    usually built with the default <varname>LOCALBASE</varname> of
%    <filename>/usr/pkg</filename>, and that you should
%    <emphasis>not</emphasis> install any if you use a non-standard
%    <varname>LOCALBASE</varname>.</para>


\subsection{Building packages from a repository checkout} % ----------------
\label{section:using:checkout}

Before building a  package, \robotpkg fetches the sources  from the official(s)
download  location(s),  as  instructed  by the  {\tt  MASTER\_SITES}  variable.
This is the standard and expected behaviour when you work with stable packages.

Occasionally, though,  it is useful to fetch  a snapshot of the  sources from a
development repository. For instance, one  might want to quickly test a release
candidate of a  package, or fix a simple  bug and create a patch  from the fix.
Whenever a package defines  the {\tt MASTER\_REPOSITORY} variable, \robotpkg is
able to temporarily  work with the repository defined in  this variable. At the
moment, {\tt cvs}, {\tt svn} and {\tt git} repositories are supported.

To enable this feature for a given package,  you have to first instruct
\robotpkg to work from a '{\tt checkout}' (instead of the stable releases) by
doing '{\tt make checkout}' in the package directory. For instance:

\begin{verbatim}
% cd robotpkg/foo/bar
% make checkout
\end{verbatim}

This sets  a permanent flag in the  {\em working} directory of  the package and
the {\em checkout}  configuration option will be retained  until the next '{\tt
make clean}'. After a '{\tt make  clean}', the configuration option is set back
to its default and \robotpkg will  work again with stable releases. This option
is set on a {\em per} package  basis only: configuring one package to work with
checkouts does not affect the behaviour of other packages.

After a '{\tt make checkout}' (and until a '{\tt make clean}'), the package has
a regular  checkout in its {\em  working} subdirectory.  You  can thus manually
edit, commit, switch branches, etc.  in  the package sources, like in any other
repository, by  first {\tt  cd}ing into the  working directory, then  using the
usual repository commands ({\tt cvs}, {\tt svn} or {\tt git}).

Of  course, the  individual  \robotpkg  targets are  still  available from  the
package  entry in  the robotpkg  hierarchy.  You  can for  instance  {\tt 'make
patch'}, {\tt 'configure'}, {\tt 'build'}, {\tt 'install'} or {\tt 'update'} as
usual. Note that  \robotpkg is not exactly stateless, and  this is most visible
when  working with  checkouts:  for  instance, after  a  successful {\tt  'make
build'}, you  have to do {\tt 'make  rebuild'} to force rebuilding  if you have
modified  the  sources.   The  same  holds  for  {\tt   'configure'}  (do  {\tt
'reconfigure'})  or {\tt  'install'} (do  {'reinstall'}, but  since  you cannot
install a package  twice, you normally have to use {\tt  'make replace'} in the
particular case of reinstalling a package).

The  {\tt  'clean'}  target  is  special,  in  that  it  removes  the  checkout
configuration  option and  all checkouted  sources, including  locally modified
sources. In order to prevent accidental deletion of precious files, you have to
confirm the cleanign with {\tt 'clean confirm'}, as in:

\begin{verbatim}
% make clean confirm
\end{verbatim}

A  final  remark:  we {\em  STRONGLY  DISCOURAGE}  the  use  of robotpkg  as  a
development tool  (i.e. using the {\tt  'checkout'} feature on  a {\em regular}
basis), for at least two reasons:

\begin{itemize}
   \item \robotpkg  is not designed  for this: it  will not really help  you in
   your  daily   development  work,   compared  to  the   manual  configuration
   installation of the software. It will sometimes create even more trouble, by
   ensuring  that all  the software  depending  on the  checkouted software  is
   up-to-date, which is not necessarily something you want to do every time you
   compile.

   \item  A checkout  breaks the  notion  of 'release'  and you  loose all  the
   benefits from working with packages.  In particular, you have no clear state
   of what is installed: you cannot easily reproduce the situation of time T at
   time T+n and don't know precisely  who requires which version of what. It is
   much  more  efficient and  robust  to release  frequently  a  software in  a
   development phase, than using a {\em rolling release} approach.
\end{itemize}

In our opinion, the {\tt 'checkout'}  target use should be limited to testing a
release candidate or  quickly fix a bug  and create a patch from  the fix, that
you commit upstream and put in the patches/ directory until the next release.


\subsection{Installing binary packages} % ----------------------------------

At the moment, installing binary packages is not documented.

\subsection{Removing packages} % -------------------------------------------

To deinstall a package, it does not matter whether it was installed from source
code or  from a  binary package.  The  {\tt robotpkg\_delete} command  does not
know it  anyway.  To delete a  package, you can just  run {\tt robotpkg\_delete
<package-name>}.  The package name can be given with or without version number.
Wildcards can  also be used  to deinstall a  set of packages, for  example {\tt
*genom*} all  packages whose  name contain  the word {\tt  genom}.  Be  sure to
include them  in quotes,  so that the  shell does  not expand them  before {\tt
robotpkg\_delete} sees them.

The {\tt -r} option is very powerful: it  removes all the packages that require
the package in question and then removes the package itself. For example:

\begin{verbatim}
% robotpkg_delete -r genom
\end{verbatim}

will remove genom and all the packages that used it; this allows
upgrading the {\tt genom} package.

\subsection{Getting information about installed packages} % ----------------

The {\tt  robotpkg\_info} shows information about installed  packages or binary
package files.


\subsection{Other administrative functions} % ------------------------------

The  {\tt robotpkg\_admin}  executes  various administrative  functions on  the
package system.

\subsection{Available {\tt make} targets} % --------------------------------
\label{section:using:targets}

The following targets are available in a package directory. They can be invoked
by   running  {\tt   make  <target>}   after   {\tt  cd}ing   into  some   {\tt
robotpkg/category/package}.

\subsubsection{Source manipulation}
\begin{description}
   \item[{\tt fetch}] Download the {\tt\$\{DISTFILES\}}.

   \item[{\tt extract}] Extract the contents of {\tt\$\{DISTFILES\}} into the
   work directory {\tt\$\{WRKDIR\}}.

   \item[{\tt patch}] Apply local patches available in {\tt\$\{PATCHDIR\}}
   (usually the {\tt patches} directory in the package).

   \item[{\tt checkout}] Extract the sources in {\tt\$\{WRKDIR\}} from
   {\tt\$\{MASTER\_REPOSITORY\}} instead of {\tt\$\{MASTER\_SITES\}}. This can
   be used to fetch a not yet released version instead of the latest
   release. This is mutually exclusive with the {\tt fetch} and {\tt extract}
   targets. See
   \xref{section:using:checkout}{section~\ref{section:using:checkout}} for
   details.

   \item[{\tt configure}] Perform the necessary actions to configure the
   sources. This may for instance involve running {\tt configure} or {\tt
   cmake}. If no configuration is required, this step simply does nothing.

   \item[{\tt build}] Or  just {\tt make}, the default  target. It compiles the
   package locally in {\tt\$\{WRKDIR\}}.

   \item[{\tt install}] Install the package into {\tt\$\{PREFIX\}}. The package
   is then available to the rest of the system. If an older version of the
   package is installed and required by other packages, this target requires
   confirmation. Otherwise, any older version of the package is first
   deinstalled.

   \item[{\tt replace}] Same as {\tt install}, but does not remove packages
   that depend on the replaced package. This saves some time, since already
   installed package are not touched, but if the replaced package is
   incompatible with the older version, you will run into trouble. Use with
   care and when you know what you are doing.

   \item[{\tt clean}] Tidy the work directory and removes {\tt\$\{WRKDIR\}}. If
   the package was extracted using {\tt checkout}, this target requires
   confirmation as it may delete locally modified files that will be lost.

   \item[{\tt update}] This is a shortcut target for {\tt fetch}, {\tt
   extract}, {\tt configure}, {\tt build}, {\tt install} and {\tt clean}. If
   the package is already installed and up-to-date, the target asks for
   confirmation.

\end{description}

\subsubsection{Introspection}
\begin{description}
   \item[{\tt show-options}] Display the list of available alternatives (see
   \xref{section:configuring:alternatives}%
   {section~\ref{section:configuring:alternatives}})
   and build options (see
   \xref{section:configuring:build_options}%
   {section~\ref{section:configuring:build_options}}).

   \item[{\tt show-depends}] Recursively display all the required dependencies
   of a package. The results are splitted between system and \robotpkg
   dependencies, and missing dependencies are indicated.

   \item[{\tt show-var}] Display the contents of a variable. This must be
   invoked as {\tt make show-var VARNAME=foo}, where {\tt foo} is the name of
   the variable to be displayed.
\end{description}

\subsubsection{Package sets}

\begin{description}
   \item[{\tt fetch-depends}, {\tt replace-depends}, {\tt update-depends}, {\tt
   clean-depends}]
   This runs the same action as {\tt fetch}, {\tt replace}, {\tt update} or
   {\tt clean} (respectively), but on all dependencies of the package,
   including the package itself. Useful to update a meta-packages, for instance.

   \item[{\tt fetch-<set>}, {\tt replace-<set>}, {\tt update-<set>}, {\tt
   clean-<set>}]
   This runs the same action as {\tt fetch}, {\tt replace}, {\tt update} or
   {\tt clean} (respectively), but on all members of the package set named {\tt
   <set>}. See
   \xref{section:configuring:sets}{section~\ref{section:configuring:sets}} 
   for an explanation of package sets and how to configure them.

\end{description}
